<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="zh-CN" lang="zh-CN">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>

<title>Asset Pipeline — Ruby on Rails Guides</title>
<link rel="stylesheet" type="text/css" href="stylesheets/style.css" />
<link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print" />

<link rel="stylesheet" type="text/css" href="stylesheets/syntaxhighlighter/shCore.css" />
<link rel="stylesheet" type="text/css" href="stylesheets/syntaxhighlighter/shThemeRailsGuides.css" />

<link rel="stylesheet" type="text/css" href="stylesheets/fixes.css" />

<link href="images/favicon.ico" rel="shortcut icon" type="image/x-icon" />
</head>
<body class="guide">
  <div id="topNav">
    <div class="wrapper">
      <strong class="more-info-label">更多内容 <a href="http://rubyonrails.org/">rubyonrails.org:</a> </strong>
      <span class="red-button more-info-button">
        更多内容
      </span>
      <ul class="more-info-links s-hidden">
        <li class="more-info"><a href="http://weblog.rubyonrails.org/">博客</a></li>
        <li class="more-info"><a href="http://guides.rubyonrails.org/">指南</a></li>
        <li class="more-info"><a href="http://api.rubyonrails.org/">API</a></li>
        <li class="more-info"><a href="http://stackoverflow.com/questions/tagged/ruby-on-rails">提问</a></li>
        <li class="more-info"><a href="https://github.com/rails/rails">到 GitHub 贡献</a></li>
        <li class="more-info"><a href="https://ruby-china.org/">Ruby China 社区</a></li>
      </ul>
    </div>
  </div>
  <div id="header">
    <div class="wrapper clearfix">
      <h1><a href="index.html" title="返回首页">Rails 指南</a></h1>
      <ul class="nav">
        <li><a class="nav-item" href="index.html">首页</a></li>
        <li class="guides-index guides-index-large">
          <a href="index.html" id="guidesMenu" class="guides-index-item nav-item">指南索引</a>
          <div id="guides" class="clearfix" style="display: none;">
            <hr />
              <dl class="L">
                <dt>新手入门</dt>
                <dd><a href="getting_started.html">Rails 入门</a></dd>
                <dt>模型</dt>
                <dd><a href="active_record_basics.html">Active Record 基础</a></dd>
                <dd><a href="active_record_migrations.html">Active Record 迁移</a></dd>
                <dd><a href="active_record_validations.html">Active Record 数据验证</a></dd>
                <dd><a href="active_record_callbacks.html">Active Record 回调</a></dd>
                <dd><a href="association_basics.html">Active Record 关联</a></dd>
                <dd><a href="active_record_querying.html">Active Record 查询接口</a></dd>
                <dt>视图</dt>
                <dd><a href="layouts_and_rendering.html">Rails 布局和视图渲染</a></dd>
                <dd><a href="form_helpers.html">Action View 表单辅助方法</a></dd>
                <dt>控制器</dt>
                <dd><a href="action_controller_overview.html">Action Controller 概览</a></dd>
                <dd><a href="routing.html">Rails 路由全解</a></dd>
              </dl>
              <dl class="R">
                <dt>深入探索</dt>
                <dd><a href="active_support_core_extensions.html">Active Support 核心扩展</a></dd>
                <dd><a href="i18n.html">Rails 国际化 API</a></dd>
                <dd><a href="action_mailer_basics.html">Action Mailer 基础</a></dd>
                <dd><a href="active_job_basics.html">Active Job 基础</a></dd>
                <dd><a href="testing.html">Rails 应用测试指南</a></dd>
                <dd><a href="security.html">Ruby on Rails 安全指南</a></dd>
                <dd><a href="debugging_rails_applications.html">调试 Rails 应用</a></dd>
                <dd><a href="configuring.html">配置 Rails 应用</a></dd>
                <dd><a href="command_line.html">Rails 命令行</a></dd>
                <dd><a href="asset_pipeline.html">Asset Pipeline</a></dd>
                <dd><a href="working_with_javascript_in_rails.html">在 Rails 中使用 JavaScript</a></dd>
                <dd><a href="autoloading_and_reloading_constants.html">自动加载和重新加载常量</a></dd>
                <dd><a href="caching_with_rails.html">Rails 缓存概览</a></dd>
                <dd><a href="api_app.html">使用 Rails 开发只提供 API 的应用</a></dd>
                <dd><a href="action_cable_overview.html">Action Cable 概览</a></dd>
                <dt>扩展 Rails</dt>
                <dd><a href="rails_on_rack.html">Rails on Rack</a></dd>
                <dd><a href="generators.html">创建及定制 Rails 生成器和模板</a></dd>
                <dt>为 Ruby on Rails 做贡献</dt>
                <dd><a href="contributing_to_ruby_on_rails.html">为 Ruby on Rails 做贡献</a></dd>
                <dd><a href="api_documentation_guidelines.html">API 文档指导方针</a></dd>
                <dd><a href="ruby_on_rails_guides_guidelines.html">Ruby on Rails 指南指导方针</a></dd>
                <dt>维护方针</dt>
                <dd><a href="maintenance_policy.html">Ruby on Rails 的维护方针</a></dd>
                <dt>发布记</dt>
                <dd><a href="upgrading_ruby_on_rails.html">Ruby on Rails 升级指南</a></dd>
                <dd><a href="5_0_release_notes.html">Ruby on Rails 5.0 发布记</a></dd>
                <dd><a href="4_2_release_notes.html">Ruby on Rails 4.2 发布记</a></dd>
                <dd><a href="4_1_release_notes.html">Ruby on Rails 4.1 发布记</a></dd>
                <dd><a href="4_0_release_notes.html">Ruby on Rails 4.0 发布记</a></dd>
                <dd><a href="3_2_release_notes.html">Ruby on Rails 3.2 发布记</a></dd>
                <dd><a href="3_1_release_notes.html">Ruby on Rails 3.1 发布记</a></dd>
                <dd><a href="3_0_release_notes.html">Ruby on Rails 3.0 发布记</a></dd>
                <dd><a href="2_3_release_notes.html">Ruby on Rails 2.3 发布记</a></dd>
                <dd><a href="2_2_release_notes.html">Ruby on Rails 2.2 发布记</a></dd>
              </dl>
          </div>
        </li>
        <li><a class="nav-item" href="contributing_to_ruby_on_rails.html">贡献</a></li>
        <li><a class="nav-item" href="credits.html">感谢</a></li>
        <li class="guides-index guides-index-small">
          <select class="guides-index-item nav-item">
            <option value="index.html">指南索引</option>
              <optgroup label="新手入门">
                  <option value="getting_started.html">Rails 入门</option>
              </optgroup>
              <optgroup label="模型">
                  <option value="active_record_basics.html">Active Record 基础</option>
                  <option value="active_record_migrations.html">Active Record 迁移</option>
                  <option value="active_record_validations.html">Active Record 数据验证</option>
                  <option value="active_record_callbacks.html">Active Record 回调</option>
                  <option value="association_basics.html">Active Record 关联</option>
                  <option value="active_record_querying.html">Active Record 查询接口</option>
              </optgroup>
              <optgroup label="视图">
                  <option value="layouts_and_rendering.html">Rails 布局和视图渲染</option>
                  <option value="form_helpers.html">Action View 表单辅助方法</option>
              </optgroup>
              <optgroup label="控制器">
                  <option value="action_controller_overview.html">Action Controller 概览</option>
                  <option value="routing.html">Rails 路由全解</option>
              </optgroup>
              <optgroup label="深入探索">
                  <option value="active_support_core_extensions.html">Active Support 核心扩展</option>
                  <option value="i18n.html">Rails 国际化 API</option>
                  <option value="action_mailer_basics.html">Action Mailer 基础</option>
                  <option value="active_job_basics.html">Active Job 基础</option>
                  <option value="testing.html">Rails 应用测试指南</option>
                  <option value="security.html">Ruby on Rails 安全指南</option>
                  <option value="debugging_rails_applications.html">调试 Rails 应用</option>
                  <option value="configuring.html">配置 Rails 应用</option>
                  <option value="command_line.html">Rails 命令行</option>
                  <option value="asset_pipeline.html">Asset Pipeline</option>
                  <option value="working_with_javascript_in_rails.html">在 Rails 中使用 JavaScript</option>
                  <option value="autoloading_and_reloading_constants.html">自动加载和重新加载常量</option>
                  <option value="caching_with_rails.html">Rails 缓存概览</option>
                  <option value="api_app.html">使用 Rails 开发只提供 API 的应用</option>
                  <option value="action_cable_overview.html">Action Cable 概览</option>
              </optgroup>
              <optgroup label="扩展 Rails">
                  <option value="rails_on_rack.html">Rails on Rack</option>
                  <option value="generators.html">创建及定制 Rails 生成器和模板</option>
              </optgroup>
              <optgroup label="为 Ruby on Rails 做贡献">
                  <option value="contributing_to_ruby_on_rails.html">为 Ruby on Rails 做贡献</option>
                  <option value="api_documentation_guidelines.html">API 文档指导方针</option>
                  <option value="ruby_on_rails_guides_guidelines.html">Ruby on Rails 指南指导方针</option>
              </optgroup>
              <optgroup label="维护方针">
                  <option value="maintenance_policy.html">Ruby on Rails 的维护方针</option>
              </optgroup>
              <optgroup label="发布记">
                  <option value="upgrading_ruby_on_rails.html">Ruby on Rails 升级指南</option>
                  <option value="5_0_release_notes.html">Ruby on Rails 5.0 发布记</option>
                  <option value="4_2_release_notes.html">Ruby on Rails 4.2 发布记</option>
                  <option value="4_1_release_notes.html">Ruby on Rails 4.1 发布记</option>
                  <option value="4_0_release_notes.html">Ruby on Rails 4.0 发布记</option>
                  <option value="3_2_release_notes.html">Ruby on Rails 3.2 发布记</option>
                  <option value="3_1_release_notes.html">Ruby on Rails 3.1 发布记</option>
                  <option value="3_0_release_notes.html">Ruby on Rails 3.0 发布记</option>
                  <option value="2_3_release_notes.html">Ruby on Rails 2.3 发布记</option>
                  <option value="2_2_release_notes.html">Ruby on Rails 2.2 发布记</option>
              </optgroup>
          </select>
        </li>
      </ul>
    </div>
  </div>
  <hr class="hide" />

  <div id="feature">
    <div class="wrapper">
      <h2>Asset Pipeline</h2><p>本文介绍 Asset Pipeline。</p><p>读完本文后，您将学到：</p>
<ul>
<li>  Asset Pipeline 是什么，有什么用处；</li>
<li>  如何合理组织应用的静态资源文件；</li>
<li>  使用 Asset Pipeline 的好处；</li>
<li>  如何为 Asset Pipeline 添加预处理器；</li>
<li>  如何用 gem 打包静态资源文件。</li>
</ul>


              <div id="subCol">
          <h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />目录</h3>
          <ol class="chapters">
<li>
<a href="#what-is-the-asset-pipeline">Asset Pipeline 是什么</a>

<ul>
<li><a href="#main-features">主要特性</a></li>
<li><a href="#what-is-fingerprinting-and-why-should-i-care">指纹识别是什么，为什么要关心指纹？</a></li>
</ul>
</li>
<li>
<a href="#how-to-use-the-asset-pipeline">如何使用 Asset Pipeline</a>

<ul>
<li><a href="#controller-specific-assets">针对控制器的静态资源文件</a></li>
<li><a href="#asset-organization">静态资源文件的组织方式</a></li>
<li><a href="#coding-links-to-assets">创建指向静态资源文件的链接</a></li>
<li><a href="#manifest-files-and-directives">清单文件和指令</a></li>
<li><a href="#preprocessing">预处理</a></li>
</ul>
</li>
<li>
<a href="#in-development">在开发环境中</a>

<ul>
<li><a href="#runtime-error-checking">检查运行时错误</a></li>
<li><a href="#raise-an-error-when-an-asset-is-not-found">找不到静态资源时抛出错误</a></li>
<li><a href="#turning-digests-off">关闭指纹</a></li>
<li><a href="#turning-debugging-off">关闭调试</a></li>
</ul>
</li>
<li>
<a href="#in-production">在生产环境中</a>

<ul>
<li><a href="#precompiling-assets">预编译静态资源文件</a></li>
<li><a href="#local-precompilation">本地预编译</a></li>
<li><a href="#live-compilation">实时编译</a></li>
<li><a href="#cdns">CDN</a></li>
</ul>
</li>
<li>
<a href="#customizing-the-pipeline">自定义 Asset Pipeline</a>

<ul>
<li><a href="#css-compression">压缩 CSS</a></li>
<li><a href="#javascript-compression">压缩 JavaScript</a></li>
<li><a href="#serving-gzipped-version-of-assets">用 GZip 压缩静态资源文件</a></li>
<li><a href="#using-your-own-compressor">自定义压缩工具</a></li>
<li><a href="#changing-the-assets-path">修改静态资源文件的路径</a></li>
<li><a href="#x-sendfile-headers"><code>X-Sendfile</code> 首部</a></li>
</ul>
</li>
<li><a href="#assets-cache-store">静态资源文件缓存的存储方式</a></li>
<li><a href="#adding-assets-to-your-gems">通过 gem 添加静态资源文件</a></li>
<li><a href="#making-your-library-or-gem-a-pre-processor">使用代码库或 gem 作为预处理器</a></li>
<li><a href="#upgrading-from-old-versions-of-rails">从旧版本的 Rails 升级</a></li>
</ol>

        </div>

    </div>
  </div>

  <div id="container">
    <div class="wrapper">
      <div id="mainCol">
        <p><a class="anchor" id="what-is-the-asset-pipeline"></a></p><h3 id="what-is-the-asset-pipeline">1 Asset Pipeline 是什么</h3><p>Asset Pipeline 提供了用于连接、简化或压缩 JavaScript 和 CSS 静态资源文件的框架。有了 Asset Pipeline，我们还可以使用其他语言和预处理器，例如 CoffeeScript、Sass 和 ERB，编写这些静态资源文件。应用中的静态资源文件还可以自动与其他 gem 中的静态资源文件合并。例如，与 <code>jquery-rails</code> gem 中包含的 <code>jquery.js</code> 文件合并，从而使 Rails 能够支持 AJAX 特性。</p><p>Asset Pipeline 是通过 <a href="https://github.com/rails/sprockets-rails">sprockets-rails</a> gem 实现的，Rails 默认启用了这个 gem。在新建 Rails 应用时，通过 <code>--skip-sprockets</code> 选项可以禁用这个 gem。</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ rails new appname --skip-sprockets

</pre>
</div>
<p>在新建 Rails 应用时，Rails 自动在 Gemfile 中添加了 <code>sass-rails</code>、<code>coffee-rails</code> 和 <code>uglifier</code> gem，Sprockets 通过这些 gem 来压缩静态资源文件：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
gem 'sass-rails'
gem 'uglifier'
gem 'coffee-rails'

</pre>
</div>
<p>使用 <code>--skip-sprockets</code> 选项时，Rails 不会在 Gemfile 中添加这些 gem。因此，之后如果想要启用 Asset Pipeline，就需要手动在 Gemfile 中添加这些 gem。此外，使用 <code>--skip-sprockets</code> 选项时生成的 <code>config/application.rb</code> 也略有不同，用于加载 <code>sprockets/railtie</code> 的代码被注释掉了，因此要启用 Asset Pipeline，还需要取消注释：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
# require "sprockets/railtie"

</pre>
</div>
<p>在 <code>production.rb</code> 配置文件中，通过 <code>config.assets.css_compressor</code> 和 <code>config.assets.js_compressor</code> 选项可以分别为 CSS 和 JavaScript 静态资源文件设置压缩方式：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.css_compressor = :yui
config.assets.js_compressor = :uglifier

</pre>
</div>
<div class="note"><p>如果 Gemfile 中包含 <code>sass-rails</code> gem，Rails 就会自动使用这个 gem 压缩 CSS 静态资源文件，而无需设置 <code>config.assets.css_compressor</code> 选项。</p></div><p><a class="anchor" id="main-features"></a></p><h4 id="main-features">1.1 主要特性</h4><p>Asset Pipeline 的特性之一是连接静态资源文件，目的是减少渲染网页时浏览器发起的请求次数。Web 浏览器能够同时发起的请求次数是有限的，因此更少的请求次数可能意味着更快的应用加载速度。</p><p>Sprockets 把所有 JavaScript 文件连接为一个主 <code>.js</code> 文件，把所有 CSS 文件连接为一个主 <code>.css</code> 文件。后文会介绍，我们可以按需定制连接文件的方式。在生产环境中，Rails 会在每个文件名中插入 SHA256 指纹，以便 Web 浏览器缓存文件。当我们修改了文件内容，Rails 会自动修改文件名中的指纹，从而让原有缓存失效。</p><p>Asset Pipeline 的特性之二是简化或压缩静态资源文件。对于 CSS 文件，会删除空格和注释。对于 JavaScript 文件，可以进行更复杂的处理，我们可以从内置选项中选择处理方式，也可以自定义处理方式。</p><p>Asset Pipeline 的特性之三是可以使用更高级的语言编写静态资源文件，再通过预编译转换为实际的静态资源文件。默认支持的高级语言有：用于编写 CSS 的 Sass，用于编写 JavaScript 的 CoffeeScript，以及 ERB。</p><p><a class="anchor" id="what-is-fingerprinting-and-why-should-i-care"></a></p><h4 id="what-is-fingerprinting-and-why-should-i-care">1.2 指纹识别是什么，为什么要关心指纹？</h4><p>指纹是一项根据文件内容修改文件名的技术。一旦文件内容发生变化，文件名就会发生变化。对于静态文件或内容很少发生变化的文件，这项技术提供了确定文件的两个版本是否相同的简单方法，特别是在跨服务器和多次部署的情况下。</p><p>当一个文件的文件名能够根据文件内容发生变化，并且能够保证不会出现重名时，就可以通过设置 HTTP 首部来建议所有缓存（CDN、ISP、网络设备或 Web 浏览器的缓存）都保存该文件的副本。一旦文件内容更新，文件名中的指纹就会发生变化，从而使远程客户端发起对文件新副本的请求。这项技术称为“缓存清除”（cache busting）。</p><p>Sprockets 使用指纹的方式是在文件名中添加文件内容的哈希值，并且通常会添加到文件名末尾。例如，对于 CSS 文件 <code>global.css</code>，添加哈希值后文件名可能变为：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
global-908e25f4bf641868d8683022a5b62f54.css

</pre>
</div>
<p>Rails 的 Asset Pipeline 也采取了这种策略。</p><p>以前 Rails 采用的策略是，通过内置的辅助方法，为每一个指向静态资源文件的链接添加基于日期生成的查询字符串。在网页源代码中，会生成下面这样的链接：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
/stylesheets/global.css?1309495796

</pre>
</div>
<p>使用查询字符串的策略有如下缺点：</p><p><strong>1. 如果一个文件的两个版本只是文件名的查询参数不同，这时不是所有缓存都能可靠地更新该文件的缓存。</strong></p><p><a href="http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/">Steve Souders</a> 建议，“……避免在可缓存的资源上使用查询字符串”。他发现，在使用查询字符串的情况下，有 5—20% 的请求不会被缓存。对于某些 CDN，通过修改查询字符串根本无法使缓存失效。</p><p><strong>2. 在多服务器环境中，不同节点上的文件名有可能发生变化。</strong></p><p>在 Rails 2.x 中，默认基于文件修改时间生成查询字符串。当静态资源文件被部署到某个节点上时，无法保证文件的时间戳保持不变，这样，对于同一个文件的请求，不同服务器可能返回不同的文件名。</p><p><strong>3. 缓存失效的情况过多。</strong></p><p>每次部署代码的新版本时，静态资源文件都会被重新部署，这些文件的最后修改时间也会发生变化。这样，不管其内容是否发生变化，客户端都不得不重新获取这些文件。</p><p>使用指纹可以避免使用查询字符串的这些缺点，并且能够确保文件内容相同时文件名也相同。</p><p>在开发环境和生产环境中，指纹都是默认启用的。通过 <code>config.assets.digest</code> 配置选项，可以启用或禁用指纹。</p><p>扩展阅读：</p>
<ul>
<li>  <a href="http://code.google.com/speed/page-speed/docs/caching.html">优化缓存</a>
</li>
<li>  <a href="http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/">为文件名添加版本号：请不要使用查询字符串</a>
</li>
</ul>
<p><a class="anchor" id="how-to-use-the-asset-pipeline"></a></p><h3 id="how-to-use-the-asset-pipeline">2 如何使用 Asset Pipeline</h3><p>在 Rails 的早期版本中，所有静态资源文件都放在 <code>public</code> 文件夹的子文件夹中，例如 <code>images</code>、<code>javascripts</code> 和 <code>stylesheets</code> 子文件夹。当 Rails 开始使用 Asset Pipeline 后，就推荐把静态资源文件放在 <code>app/assets</code> 文件夹中，并使用 Sprockets 中间件处理这些文件。</p><p>当然，静态资源文件仍然可以放在 <code>public</code> 文件夹及其子文件夹中。只要把 <code>config.public_file_server.enabled</code> 选项设置为 <code>true</code>，Rails 应用或 Web 服务器就会处理 <code>public</code> 文件夹及其子文件夹中的所有静态资源文件。但对于需要预处理的文件，都应该放在 <code>app/assets</code> 文件夹中。</p><p>在生产环境中，Rails 默认会对 <code>public/assets</code> 文件夹中的文件进行预处理。经过预处理的静态资源文件将由 Web 服务器直接处理。在生产环境中，<code>app/assets</code> 文件夹中的文件不会直接交由 Web 服务器处理。</p><p><a class="anchor" id="controller-specific-assets"></a></p><h4 id="controller-specific-assets">2.1 针对控制器的静态资源文件</h4><p>当我们使用生成器生成脚手架或控制器时，Rails 会同时为控制器生成 JavaScript 文件（如果 Gemfile 中包含了 <code>coffee-rails</code> gem，那么生成的是 CoffeeScript 文件）和 CSS 文件（如果 Gemfile 中包含了 <code>sass-rails</code> gem，那么生成的是 SCSS 文件）。此外，在生成脚手架时，Rails 还会生成 <code>scaffolds.css</code> 文件（如果 Gemfile 中包含了 <code>sass-rails</code> gem，那么生成的是 <code>scaffolds.scss</code> 文件）。</p><p>例如，当我们生成 <code>ProjectsController</code> 时，Rails 会新建 <code>app/assets/javascripts/projects.coffee</code> 文件和 <code>app/assets/stylesheets/projects.scss</code> 文件。默认情况下，应用会通过 <code>require_tree</code> 指令引入这两个文件。关于 <code>require_tree</code> 指令的更多介绍，请参阅 <a href="#manifest-files-and-directives">清单文件和指令</a>。</p><p>针对控制器的 JavaScript 文件和 CSS 文件也可以只在相应的控制器中引入：</p><p><code>&lt;%= javascript_include_tag params[:controller] %&gt;</code> 或 <code>&lt;%= stylesheet_link_tag params[:controller] %&gt;</code></p><p>此时，千万不要使用 <code>require_tree</code> 指令，否则就会重复包含这些静态资源文件。</p><div class="warning"><p>在进行静态资源文件预编译时，请确保针对控制器的静态文件是在按页加载时进行预编译的。默认情况下，Rails 不会自动对 <code>.coffee</code> 和 <code>.scss</code> 文件进行预编译。关于预编译工作原理的更多介绍，请参阅 <a href="#precompiling-assets">预编译静态资源文件</a>。</p></div><div class="note"><p>要使用 CoffeeScript，就必须安装支持 ExecJS 的运行时。macOS 和 Windows 已经预装了此类运行时。关于所有可用运行时的更多介绍，请参阅 <a href="https://github.com/rails/execjs#readme">ExecJS</a> 文档。</p></div><p>通过在 <code>config/application.rb</code> 配置文件中添加下述代码，可以禁止生成针对控制器的静态资源文件：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.generators do |g|
  g.assets false
end

</pre>
</div>
<p><a class="anchor" id="asset-organization"></a></p><h4 id="asset-organization">2.2 静态资源文件的组织方式</h4><p>应用的 Asset Pipeline 静态资源文件可以储存在三个位置：<code>app/assets</code>、<code>lib/assets</code> 和 <code>vendor/assets</code>。</p>
<ul>
<li>  <code>app/assets</code> 文件夹用于储存应用自有的静态资源文件，例如自定义图像、JavaScript 文件和 CSS 文件。</li>
<li>  <code>lib/assets</code> 文件夹用于储存自有代码库的静态资源文件，这些代码库或者不适合放在当前应用中，或者需要在多个应用间共享。</li>
<li>  <code>vendor/assets</code> 文件夹用于储存第三方代码库的静态资源文件，例如 JavaScript 插件和 CSS 框架。如果第三方代码库中引用了同样由 Asset Pipeline 处理的静态资源文件（图像、CSS 文件等），就必须使用 <code>asset_path</code> 这样的辅助方法重新编写相关代码。</li>
</ul>
<div class="warning"><p>从 Rails 3 升级而来的用户需要注意，通过设置应用的清单文件， 我们可以包含 <code>lib/assets</code> 和 <code>vendor/assets</code> 文件夹中的静态资源文件，但是这两个文件夹不再是预编译数组的一部分。更多介绍请参阅 <a href="#precompiling-assets">预编译静态资源文件</a>。</p></div><p><a class="anchor" id="search-paths"></a></p><h5 id="search-paths">2.2.1 搜索路径</h5><p>当清单文件或辅助方法引用了静态资源文件时，Sprockets 会在静态资源文件的三个默认存储位置中进行查找。</p><p>这三个默认存储位置分别是 <code>app/assets</code> 文件夹的 <code>images</code>、<code>javascripts</code> 和 <code>stylesheets</code> 子文件夹，实际上这三个文件夹并没有什么特别之处，所有的 <code>app/assets/*</code> 文件夹及其子文件夹都会被搜索。</p><p>例如，下列文件：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
app/assets/javascripts/home.js
lib/assets/javascripts/moovinator.js
vendor/assets/javascripts/slider.js
vendor/assets/somepackage/phonebox.js

</pre>
</div>
<p>在清单文件中可以像下面这样进行引用：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
//= require home
//= require moovinator
//= require slider
//= require phonebox

</pre>
</div>
<p>这些文件夹的子文件夹中的静态资源文件：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
app/assets/javascripts/sub/something.js

</pre>
</div>
<p>可以像下面这样进行引用：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
//= require sub/something

</pre>
</div>
<p>通过在 Rails 控制台中检查 <code>Rails.application.config.assets.paths</code> 变量，我们可以查看搜索路径。</p><p>除了标准的 <code>app/assets/*</code> 路径，还可以在 <code>config/application.rb</code> 配置文件中为 Asset Pipeline 添加其他路径。例如：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.paths &lt;&lt; Rails.root.join("lib", "videoplayer", "flash")

</pre>
</div>
<p>Rails 会按照路径在搜索路径中出现的先后顺序，对路径进行遍历。因此，在默认情况下，<code>app/assets</code> 中的文件优先级最高，将会遮盖 <code>lib</code> 和 <code>vendor</code> 文件夹中的同名文件。</p><p>千万注意，在清单文件之外引用的静态资源文件必须添加到预编译数组中，否则无法在生产环境中使用。</p><p><a class="anchor" id="using-index-files"></a></p><h5 id="using-index-files">2.2.2 使用索引文件</h5><p>对于 Sprockets，名为 <code>index</code>（带有相关扩展名）的文件具有特殊用途。</p><p>例如，假设应用中使用的 jQuery 库及多个模块储存在 <code>lib/assets/javascripts/library_name</code> 文件夹中，那么 <code>lib/assets/javascripts/library_name/index.js</code> 文件将作为这个库的清单文件。在这个库的清单文件中，应该按顺序列出所有需要加载的文件，或者干脆使用 <code>require_tree</code> 指令。</p><p>在应用的清单文件中，可以把这个库作为一个整体加载：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
//= require library_name

</pre>
</div>
<p>这样，相关代码总是作为整体在应用中使用，降低了维护成本，并使代码保持简洁。</p><p><a class="anchor" id="coding-links-to-assets"></a></p><h4 id="coding-links-to-assets">2.3 创建指向静态资源文件的链接</h4><p>Sprockets 没有为访问静态资源文件添加任何新方法，而是继续使用我们熟悉的 <code>javascript_include_tag</code> 和 <code>stylesheet_link_tag</code> 辅助方法：</p><div class="code_container">
<pre class="brush: ruby; html-script: true; gutter: false; toolbar: false">
&lt;%= stylesheet_link_tag "application", media: "all" %&gt;
&lt;%= javascript_include_tag "application" %&gt;

</pre>
</div>
<p>如果使用了 Rails 默认包含的 <code>turbolinks</code> gem，并使用了 <code>data-turbolinks-track</code> 选项，Turbolinks 就会检查静态资源文件是否有更新，如果有更新就加载到页面中：</p><div class="code_container">
<pre class="brush: ruby; html-script: true; gutter: false; toolbar: false">
&lt;%= stylesheet_link_tag "application", media: "all", "data-turbolinks-track" =&gt; "reload" %&gt;
&lt;%= javascript_include_tag "application", "data-turbolinks-track" =&gt; "reload" %&gt;

</pre>
</div>
<p>在常规视图中，我们可以像下面这样访问 <code>app/assets/images</code> 文件夹中的图像：</p><div class="code_container">
<pre class="brush: ruby; html-script: true; gutter: false; toolbar: false">
&lt;%= image_tag "rails.png" %&gt;

</pre>
</div>
<p>如果在应用中启用了 Asset Pipeline，并且未在当前环境中禁用 Asset Pipeline，那么这个图像文件将由 Sprockets 处理。如果图像的位置是 <code>public/assets/rails.png</code>，那么将由 Web 服务器处理。</p><p>如果文件请求包含 SHA256 哈希值，例如 <code>public/assets/rails-f90d8a84c707a8dc923fca1ca1895ae8ed0a09237f6992015fef1e11be77c023.png</code>，处理的方式也是一样的。关于如何生成哈希值的介绍，请参阅 <a href="#in-production">在生产环境中</a>。</p><p>Sprockets 还会检查 <code>config.assets.paths</code> 中指定的路径，其中包括 Rails 应用的标准路径和 Rails 引擎添加的路径。</p><p>也可以把图像放在子文件夹中，访问时只需加上子文件夹的名称即可：</p><div class="code_container">
<pre class="brush: ruby; html-script: true; gutter: false; toolbar: false">
&lt;%= image_tag "icons/rails.png" %&gt;

</pre>
</div>
<div class="warning"><p>如果对静态资源文件进行了预编译（请参阅 <a href="#in-production">在生产环境中</a>），那么在页面中链接到并不存在的静态资源文件或空字符串将导致该页面抛出异常。因此，在使用 <code>image_tag</code> 等辅助方法处理用户提供的数据时一定要小心。</p></div><p><a class="anchor" id="css-and-erb"></a></p><h5 id="css-and-erb">2.3.1 CSS 和 ERB</h5><p>Asset Pipeline 会自动计算 ERB 的值。也就是说，只要给 CSS 文件添加 <code>.erb</code> 扩展名（例如 <code>application.css.erb</code>），就可以在 CSS 规则中使用 <code>asset_path</code> 等辅助方法。</p><div class="code_container">
<pre class="brush: ruby; html-script: true; gutter: false; toolbar: false">
.class { background-image: url(&lt;%= asset_path 'image.png' %&gt;) }

</pre>
</div>
<p>上述代码中的 <code>asset_path</code> 辅助方法会返回指向图像真实路径的链接。图像必须位于静态文件加载路径中，例如 <code>app/assets/images/image.png</code>，以便在这里引用。如果在 <code>public/assets</code> 文件夹中已经存在此图像的带指纹的版本，那么将引用这个带指纹的版本。</p><p>要想使用 <a href="http://en.wikipedia.org/wiki/Data_URI_scheme">data URI</a>（用于把图像数据直接嵌入 CSS 文件中），可以使用 <code>asset_data_uri</code> 辅助方法：</p><div class="code_container">
<pre class="brush: ruby; html-script: true; gutter: false; toolbar: false">
#logo { background: url(&lt;%= asset_data_uri 'logo.png' %&gt;) }

</pre>
</div>
<p><code>asset_data_uri</code> 辅助方法会把正确格式化后的 data URI 插入 CSS 源代码中。</p><p>注意，关闭标签不能使用 <code>-%&gt;</code> 形式。</p><p><a class="anchor" id="css-and-sass"></a></p><h5 id="css-and-sass">2.3.2 CSS 和 Sass</h5><p>在使用 Asset Pipeline 时，静态资源文件的路径都必须重写，为此 <code>sass-rails</code> gem 提供了 <code>-url</code> 和 <code>-path</code> 系列辅助方法（在 Sass 中使用连字符，在 Ruby 中使用下划线），用于处理图像、字体、视频、音频、JavaScript 和 CSS 等类型的静态资源文件。</p>
<ul>
<li>  <code>image-url("rails.png")</code> 会返回 <code>url(/assets/rails.png)</code>
</li>
<li>  <code>image-path("rails.png")</code> 会返回 <code>"/assets/rails.png"</code>
</li>
</ul>
<p>或使用更通用的形式：</p>
<ul>
<li>  <code>asset-url("rails.png")</code> 返回 <code>url(/assets/rails.png)</code>
</li>
<li>  <code>asset-path("rails.png")</code> 返回 <code>"/assets/rails.png"</code>
</li>
</ul>
<p><a class="anchor" id="javascript-coffeescript-and-erb"></a></p><h5 id="javascript-coffeescript-and-erb">2.3.3 JavaScript/CoffeeScript 和 ERB</h5><p>只要给 JavaScript 文件添加 <code>.erb</code> 扩展名（例如 <code>application.js.erb</code>），就可以在 JavaScript 源代码中使用 <code>asset_path</code> 辅助方法：</p><div class="code_container">
<pre class="brush: ruby; html-script: true; gutter: false; toolbar: false">
$('#logo').attr({ src: "&lt;%= asset_path('logo.png') %&gt;" });

</pre>
</div>
<p>上述代码中的 <code>asset_path</code> 辅助方法会返回指向图像真实路径的链接。</p><p>同样，只要给 CoffeeScript 文件添加 <code>.erb</code> 扩展名（例如 <code>application.coffee.erb</code>），就可以在 CoffeeScript 源代码中使用 <code>asset_path</code> 辅助方法：</p><div class="code_container">
<pre class="brush: ruby; html-script: true; gutter: false; toolbar: false">
$('#logo').attr src: "&lt;%= asset_path('logo.png') %&gt;"

</pre>
</div>
<p><a class="anchor" id="manifest-files-and-directives"></a></p><h4 id="manifest-files-and-directives">2.4 清单文件和指令</h4><p>Sprockets 使用清单文件来确定需要包含和处理哪些静态资源文件。这些清单文件中的指令会告诉 Sprockets，要想创建 CSS 或 JavaScript 文件需要加载哪些文件。通过这些指令，可以让 Sprockets 加载指定文件，对这些文件进行必要的处理，然后把它们连接为单个文件，最后进行压缩（压缩方式取决于 <code>Rails.application.config.assets.js_compressor</code> 选项的值）。这样在页面中只需处理一个文件而非多个文件，减少了浏览器的请求次数，大大缩短了页面的加载时间。通过压缩还能使文件变小，使浏览器可以更快地下载。</p><p>例如，在默认情况下，新建 Rails 应用的 <code>app/assets/javascripts/application.js</code> 文件包含下面几行代码：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
// ...
//= require jquery
//= require jquery_ujs
//= require_tree .

</pre>
</div>
<p>在 JavaScript 文件中，Sprockets 指令以 <code>//=.</code> 开头。上述代码中使用了 <code>require</code> 和 <code>require_tree</code> 指令。<code>require</code> 指令用于告知 Sprockets 哪些文件需要加载。这里加载的是 Sprockets 搜索路径中的 <code>jquery.js</code> 和 <code>jquery_ujs.js</code> 文件。我们不必显式提供文件的扩展名，因为 Sprockets 假定在 <code>.js</code> 文件中加载的总是 <code>.js</code> 文件。</p><p><code>require_tree</code> 指令告知 <code>Sprockets</code> 以递归方式包含指定文件夹中的所有 JavaScript 文件。在指定文件夹路径时，必须使用相对于清单文件的相对路径。也可以通过 <code>require_directory</code> 指令包含指定文件夹中的所有 JavaScript 文件，此时将不会采取递归方式。</p><p>清单文件中的指令是按照从上到下的顺序处理的，但我们无法确定 <code>require_tree</code> 指令包含文件的顺序，因此不应该依赖于这些文件的顺序。如果想要确保连接文件时某些 JavaScript 文件出现在其他 JavaScript 文件之前，可以在清单文件中先行加载这些文件。注意，<code>require</code> 系列指令不会重复加载文件。</p><p>在默认情况下，新建 Rails 应用的 <code>app/assets/stylesheets/application.css</code> 文件包含下面几行代码：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
/* ...
*= require_self
*= require_tree .
*/

</pre>
</div>
<p>无论新建 Rails 应用时是否使用了 <code>--skip-sprockets</code> 选项，Rails 都会创建 <code>app/assets/javascripts/application.js</code> 和 <code>app/assets/stylesheets/application.css</code> 文件。因此，之后想要使用 Asset Pipeline 非常容易。</p><p>我们在 JavaScript 文件中使用的指令同样可以在 CSS 文件中使用，此时加载的是 CSS 文件而不是 JavaScript 文件。在 CSS 清单文件中，<code>require_tree</code> 指令的工作原理和在 JavaScript 清单文件中相同，会加载指定文件夹中的所有 CSS 文件。</p><p>上述代码中使用了 <code>require_self</code> 指令，用于把当前文件中的 CSS 代码（如果存在）插入调用这个指令的位置。</p><div class="note"><p>要想使用多个 Sass 文件，通常应该使用 <a href="http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#import">Sass @import 规则</a>，而不是 Sprockets 指令。如果使用 Sprockets 指令，这些 Sass 文件将拥有各自的作用域，这样变量和混入只能在定义它们的文件中使用。</p></div><p>和使用 <code>require_tree</code> 指令相比，使用 <code>@import "*"</code> 和 <code>@import "**/*"</code> 的效果完全相同，都能加载指定文件夹中的所有文件。更多介绍和注意事项请参阅 <a href="https://github.com/rails/sass-rails#features">sass-rails 文档</a>。</p><p>我们可以根据需要使用多个清单文件。例如，可以用 <code>admin.js</code> 和 <code>admin.css</code> 清单文件分别包含应用管理后台的 JS 和 CSS 文件。</p><p>CSS 清单文件中指令的执行顺序类似于前文介绍的 JavaScript 清单文件，尤其是加载的文件都会按照指定顺序依次编译。例如，我们可以像下面这样把 3 个 CSS 文件连接在一起：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
/* ...
*= require reset
*= require layout
*= require chrome
*/

</pre>
</div>
<p><a class="anchor" id="preprocessing"></a></p><h4 id="preprocessing">2.5 预处理</h4><p>静态资源文件的扩展名决定了预处理的方式。在使用默认的 Rails gemset 生成控制器或脚手架时，会生成 CoffeeScript 和 SCSS 文件，而不是普通的 JavaScript 和 CSS 文件。在前文的例子中，生成 <code>projects</code> 控制器时会生成 <code>app/assets/javascripts/projects.coffee</code> 和 <code>app/assets/stylesheets/projects.scss</code> 文件。</p><p>在开发环境中，或 Asset Pipeline 被禁用时，会使用 <code>coffee-script</code> 和 <code>sass</code> gem 提供的处理器分别处理相应的文件请求，并把生成的 JavaScript 和 CSS 文件发给浏览器。当 Asset Pipeline 可用时，会对这些文件进行预处理，然后储存在 <code>public/assets</code> 文件夹中，由 Rails 应用或 Web 服务器处理。</p><p>通过添加其他扩展名，可以对文件进行更多预处理。对扩展名的解析顺序是从右到左，相应的预处理顺序也是从右到左。例如，对于 <code>app/assets/stylesheets/projects.scss.erb</code> 文件，会先处理 ERB，再处理 SCSS，最后作为 CSS 文件处理。同样，对于 <code>app/assets/javascripts/projects.coffee.erb</code> 文件，会先处理 ERB，再处理 CoffeeScript，最后作为 JavaScript 文件处理。</p><p>记住预处理顺序很重要。例如，如果我们把文件名写为 <code>app/assets/javascripts/projects.erb.coffee</code>，就会先处理 CoffeeScript，这时一旦遇到 ERB 代码就会出错。</p><p><a class="anchor" id="in-development"></a></p><h3 id="in-development">3 在开发环境中</h3><p>在开发环境中，Asset Pipeline 会按照清单文件中指定的顺序处理静态资源文件。</p><p>对于清单文件 <code>app/assets/javascripts/application.js</code>：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
//= require core
//= require projects
//= require tickets

</pre>
</div>
<p>会生成下面的 HTML：</p><div class="code_container">
<pre class="brush: xml; gutter: false; toolbar: false">
&lt;script src="/assets/core.js?body=1"&gt;&lt;/script&gt;
&lt;script src="/assets/projects.js?body=1"&gt;&lt;/script&gt;
&lt;script src="/assets/tickets.js?body=1"&gt;&lt;/script&gt;

</pre>
</div>
<p>其中 <code>body</code> 参数是使用 Sprockets 时必须使用的参数。</p><p><a class="anchor" id="runtime-error-checking"></a></p><h4 id="runtime-error-checking">3.1 检查运行时错误</h4><p>在生产环境中，Asset Pipeline 默认会在运行时检查潜在错误。要想禁用此行为，可以设置：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.raise_runtime_errors = false

</pre>
</div>
<p>当此选项设置为 <code>true</code> 时，Asset Pipeline 会检查应用中加载的所有静态资源文件是否都已包含在 <code>config.assets.precompile</code> 列表中。如果此时 <code>config.assets.digest</code> 也设置为 <code>true</code>，Asset Pipeline 会要求所有对静态资源文件的请求都包含指纹（digest）。</p><p><a class="anchor" id="raise-an-error-when-an-asset-is-not-found"></a></p><h4 id="raise-an-error-when-an-asset-is-not-found">3.2 找不到静态资源时抛出错误</h4><p>如果使用的 sprockets-rails 是 3.2.0 或以上版本，可以配置找不到静态资源时的行为。如果禁用了“静态资源后备机制”，找不到静态资源时抛出错误。</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.unknown_asset_fallback = false

</pre>
</div>
<p>如果启用了“静态资源后备机制”，找不到静态资源时，输出路径，而不抛出错误。静态资源后备机制默认启用。</p><p><a class="anchor" id="turning-digests-off"></a></p><h4 id="turning-digests-off">3.3 关闭指纹</h4><p>通过修改 <code>config/environments/development.rb</code> 配置文件，我们可以关闭指纹：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.digest = false

</pre>
</div>
<p>当此选项设置为 <code>true</code> 时，Rails 会为静态资源文件的 URL 生成指纹。</p><p><a class="anchor" id="turning-debugging-off"></a></p><h4 id="turning-debugging-off">3.4 关闭调试</h4><p>通过修改 <code>config/environments/development.rb</code> 配置文件，我们可以关闭调式模式：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.debug = false

</pre>
</div>
<p>当调试模式关闭时，Sprockets 会对所有文件进行必要的预处理，然后把它们连接起来。此时，前文的清单文件会生成下面的 HTML：</p><div class="code_container">
<pre class="brush: xml; gutter: false; toolbar: false">
&lt;script src="/assets/application.js"&gt;&lt;/script&gt;

</pre>
</div>
<p>当服务器启动后，静态资源文件将在第一次请求时进行编译和缓存。Sprockets 通过设置 <code>must-revalidate Cache-Control</code> HTTP 首部，来减少后续请求造成的开销，此时对于后续请求浏览器会得到 304（未修改）响应。</p><p>如果清单文件中的某个文件在两次请求之间发生了变化，服务器会使用新编译的文件作为响应。</p><p>还可以通过 Rails 辅助方法启用调试模式：</p><div class="code_container">
<pre class="brush: ruby; html-script: true; gutter: false; toolbar: false">
&lt;%= stylesheet_link_tag "application", debug: true %&gt;
&lt;%= javascript_include_tag "application", debug: true %&gt;

</pre>
</div>
<p>当然，如果已经启用了调式模式，再使用 <code>:debug</code> 选项就完全是多余的了。</p><p>在开发模式中，我们也可以启用压缩功能以检查其工作是否正常，在需要进行调试时再禁用压缩功能。</p><p><a class="anchor" id="in-production"></a></p><h3 id="in-production">4 在生产环境中</h3><p>在生产环境中，Sprockets 会使用前文介绍的指纹机制。默认情况下，Rails 假定静态资源文件都经过了预编译，并将由 Web 服务器处理。</p><p>在预编译阶段，Sprockets 会根据静态资源文件的内容生成 SHA256 哈希值，并在保存文件时把这个哈希值添加到文件名中。Rails 辅助方法会用这些包含指纹的文件名代替清单文件中的文件名。</p><p>例如，下面的代码：</p><div class="code_container">
<pre class="brush: ruby; html-script: true; gutter: false; toolbar: false">
&lt;%= javascript_include_tag "application" %&gt;
&lt;%= stylesheet_link_tag "application" %&gt;

</pre>
</div>
<p>会生成下面的 HTML：</p><div class="code_container">
<pre class="brush: xml; gutter: false; toolbar: false">
&lt;script src="/assets/application-908e25f4bf641868d8683022a5b62f54.js"&gt;&lt;/script&gt;
&lt;link href="/assets/application-4dd5b109ee3439da54f5bdfd78a80473.css" media="screen"
rel="stylesheet" /&gt;

</pre>
</div>
<div class="note"><p>Rails 开始使用 Asset Pipeline 后，不再使用 <code>:cache</code> 和 <code>:concat</code> 选项，因此在调用 <code>javascript_include_tag</code> 和 <code>stylesheet_link_tag</code> 辅助方法时需要删除这些选项。</p></div><p>可以通过 <code>config.assets.digest</code> 初始化选项（默认为 <code>true</code>）启用或禁用指纹功能。</p><div class="note"><p>在正常情况下，请不要修改默认的 <code>config.assets.digest</code> 选项（默认为 <code>true</code>）。如果文件名中未包含指纹，并且 HTTP 头信息的过期时间设置为很久以后，远程客户端将无法在文件内容发生变化时重新获取文件。</p></div><p><a class="anchor" id="precompiling-assets"></a></p><h4 id="precompiling-assets">4.1 预编译静态资源文件</h4><p>Rails 提供了一个 Rake 任务，用于编译 Asset Pipeline 清单文件中的静态资源文件和其他相关文件。</p><p>经过编译的静态资源文件将储存在 <code>config.assets.prefix</code> 选项指定的路径中，默认为 <code>/assets</code> 文件夹。</p><p>部署 Rails 应用时可以在服务器上执行这个 Rake 任务，以便直接在服务器上完成静态资源文件的编译。关于本地编译的介绍，请参阅下一节。</p><p>这个 Rake 任务是：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ RAILS_ENV=production bin/rails assets:precompile

</pre>
</div>
<p>Capistrano（v2.15.1 及更高版本）提供了对这个 Rake 任务的支持。只需把下面这行代码添加到 <code>Capfile</code> 中：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
load 'deploy/assets'

</pre>
</div>
<p>就会把 <code>config.assets.prefix</code> 选项指定的文件夹链接到 <code>shared/assets</code> 文件夹。当然，如果 <code>shared/assets</code> 文件夹已经用于其他用途，我们就得自己编写部署任务了。</p><p>需要注意的是，<code>shared/assets</code> 文件夹会在多次部署之间共享，这样引用了这些静态资源文件的远程客户端的缓存页面在其生命周期中就能正常工作。</p><p>编译文件时的默认匹配器（matcher）包括 <code>application.js</code>、<code>application.css</code>，以及 <code>app/assets</code> 文件夹和 gem 中的所有非 JS/CSS 文件（会自动包含所有图像）：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
[ Proc.new { |filename, path| path =~ /app\/assets/ &amp;&amp; !%w(.js .css).include?(File.extname(filename)) },
/application.(css|js)$/ ]

</pre>
</div>
<div class="note"><p>这个匹配器（及预编译数组的其他成员；见后文）会匹配编译后的文件名，这意味着无论是 JS/CSS 文件，还是能够编译为 JS/CSS 的文件，都将被排除在外。例如，<code>.coffee</code> 和 <code>.scss</code> 文件能够编译为 JS/CSS，因此被排除在默认的编译范围之外。</p></div><p>要想包含其他清单文件，或单独的 JavaScript 和 CSS 文件，可以把它们添加到 <code>config/initializers/assets.rb</code> 配置文件的 <code>precompile</code> 数组中：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
Rails.application.config.assets.precompile += %w( admin.js admin.css )

</pre>
</div>
<div class="note"><p>添加到 <code>precompile</code> 数组的文件名应该以 <code>.js</code> 或 <code>.css</code> 结尾，即便实际添加的是 CoffeeScript 或 Sass 文件也是如此。</p></div><p><code>assets:precompile</code> 这个 Rake 任务还会成生 <code>.sprockets-manifest-md5hash.json</code> 文件（其中 <code>md5hash</code> 是一个 MD5 哈希值），其内容是所有静态资源文件及其指纹的列表。有了这个文件，Rails 辅助方法不需要 Sprockets 就能获得静态资源文件对应的指纹。下面是一个典型的 <code>.sprockets-manifest-md5hash.json</code> 文件的例子：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
{"files":{"application-aee4be71f1288037ae78b997df388332edfd246471b533dcedaa8f9fe156442b.js":{"logical_path":"application.js","mtime":"2016-12-23T20:12:03-05:00","size":412383,
"digest":"aee4be71f1288037ae78b997df388332edfd246471b533dcedaa8f9fe156442b","integrity":"sha256-ruS+cfEogDeueLmX3ziDMu39JGRxtTPc7aqPn+FWRCs="},
"application-86a292b5070793c37e2c0e5f39f73bb387644eaeada7f96e6fc040a028b16c18.css":{"logical_path":"application.css","mtime":"2016-12-23T19:12:20-05:00","size":2994,
"digest":"86a292b5070793c37e2c0e5f39f73bb387644eaeada7f96e6fc040a028b16c18","integrity":"sha256-hqKStQcHk8N+LA5fOfc7s4dkTq6tp/lub8BAoCixbBg="},
"favicon-8d2387b8d4d32cecd93fa3900df0e9ff89d01aacd84f50e780c17c9f6b3d0eda.ico":{"logical_path":"favicon.ico","mtime":"2016-12-23T20:11:00-05:00","size":8629,
"digest":"8d2387b8d4d32cecd93fa3900df0e9ff89d01aacd84f50e780c17c9f6b3d0eda","integrity":"sha256-jSOHuNTTLOzZP6OQDfDp/4nQGqzYT1DngMF8n2s9Dto="},
"my_image-f4028156fd7eca03584d5f2fc0470df1e0dbc7369eaae638b2ff033f988ec493.png":{"logical_path":"my_image.png","mtime":"2016-12-23T20:10:54-05:00","size":23414,
"digest":"f4028156fd7eca03584d5f2fc0470df1e0dbc7369eaae638b2ff033f988ec493","integrity":"sha256-9AKBVv1+ygNYTV8vwEcN8eDbxzaequY4sv8DP5iOxJM="}},
"assets":{"application.js":"application-aee4be71f1288037ae78b997df388332edfd246471b533dcedaa8f9fe156442b.js",
"application.css":"application-86a292b5070793c37e2c0e5f39f73bb387644eaeada7f96e6fc040a028b16c18.css",
"favicon.ico":"favicon-8d2387b8d4d32cecd93fa3900df0e9ff89d01aacd84f50e780c17c9f6b3d0eda.ico",
"my_image.png":"my_image-f4028156fd7eca03584d5f2fc0470df1e0dbc7369eaae638b2ff033f988ec493.png"}}

</pre>
</div>
<p><code>.sprockets-manifest-md5hash.json</code> 文件默认位于 <code>config.assets.prefix</code> 选项所指定的位置的根目录（默认为 <code>/assets</code> 文件夹）。</p><div class="note"><p>在生产环境中，如果有些预编译后的文件丢失了，Rails 就会抛出 <code>Sprockets::Helpers::RailsHelper::AssetPaths::AssetNotPrecompiledError</code> 异常，提示所丢失文件的文件名。</p></div><p><a class="anchor" id="far-future-expires-header"></a></p><h5 id="far-future-expires-header">4.1.1 在 HTTP 首部中设置为很久以后才过期</h5><p>预编译后的静态资源文件储存在文件系统中，并由 Web 服务器直接处理。默认情况下，这些文件的 HTTP 首部并不会在很久以后才过期，为了充分发挥指纹的作用，我们需要修改服务器配置中的请求头过期时间。</p><p>对于 Apache：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
# 在启用 Apache 模块 `mod_expires` 的情况下，才能使用
# Expires* 系列指令。
&lt;Location /assets/&gt;
  # 在使用 Last-Modified 的情况下，不推荐使用 ETag
  Header unset ETag
  FileETag None
  # RFC 规定缓存时间为 1 年
  ExpiresActive On
  ExpiresDefault "access plus 1 year"
&lt;/Location&gt;

</pre>
</div>
<p>对于 Nginx：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
location ~ ^/assets/ {
  expires 1y;
  add_header Cache-Control public;

  add_header ETag "";
}

</pre>
</div>
<p><a class="anchor" id="local-precompilation"></a></p><h4 id="local-precompilation">4.2 本地预编译</h4><p>在本地预编译静态资源文件的理由如下：</p>
<ul>
<li>  可能没有生产环境服务器文件系统的写入权限；</li>
<li>  可能需要部署到多台服务器，不想重复编译；</li>
<li>  部署可能很频繁，但静态资源文件很少变化。</li>
</ul>
<p>本地编译允许我们把编译后的静态资源文件纳入源代码版本控制，并按常规方式部署。</p><p>有三个注意事项：</p>
<ul>
<li>  不要运行用于预编译静态资源文件的 Capistrano 部署任务；</li>
<li>  开发环境中必须安装压缩或简化静态资源文件所需的工具；</li>
<li>  必须修改下面这个设置：</li>
</ul>
<p>在 <code>config/environments/development.rb</code> 配置文件中添加下面这行代码：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.prefix = "/dev-assets"

</pre>
</div>
<p>在开发环境中，通过修改 <code>prefix</code>，可以让 Sprockets 使用不同的 URL 处理静态资源文件，并把所有请求都交给 Sprockets 处理。在生产环境中，<code>prefix</code> 仍然应该设置为 <code>/assets</code>。在开发环境中，如果不修改 <code>prefix</code>，应用就会优先读取 <code>/assets</code> 文件夹中预编译后的静态资源文件，这样对静态资源文件进行修改后，除非重新编译，否则看不到任何效果。</p><p>实际上，通过修改 <code>prefix</code>，我们可以在本地预编译静态资源文件，并把这些文件储存在工作目录中，同时可以根据需要随时将其纳入源代码版本控制。开发模式将按我们的预期正常工作。</p><p><a class="anchor" id="live-compilation"></a></p><h4 id="live-compilation">4.3 实时编译</h4><p>在某些情况下，我们需要使用实时编译。在实时编译模式下，Asset Pipeline 中的所有静态资源文件都由 Sprockets 直接处理。</p><p>通过如下设置可以启用实时编译：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.compile = true

</pre>
</div>
<p>如前文所述，静态资源文件会在首次请求时被编译和缓存，辅助方法会把清单文件中的文件名转换为带 SHA256 哈希值的版本。</p><p>Sprockets 还会把 <code>Cache-Control</code> HTTP 首部设置为 <code>max-age=31536000</code>，意思是服务器和客户端浏览器的所有缓存的过期时间是 1 年。这样在本地浏览器缓存或中间缓存中找到所需静态资源文件的可能性会大大增加，从而减少从服务器上获取静态资源文件的请求次数。</p><p>但是实时编译模式会使用更多内存，性能也比默认设置更差，因此并不推荐使用。</p><p>如果部署应用的生产服务器没有预装 JavaScript 运行时，可以在 Gemfile 中添加一个：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
group :production do
  gem 'therubyracer'
end

</pre>
</div>
<p><a class="anchor" id="cdns"></a></p><h4 id="cdns">4.4 CDN</h4><p>CDN 的意思是<a href="http://en.wikipedia.org/wiki/Content_delivery_network">内容分发网络</a>，主要用于缓存全世界的静态资源文件。当 Web 浏览器请求静态资源文件时，CDN 会从地理位置最近的 CDN 服务器上发送缓存的文件副本。如果我们在生产环境中让 Rails 直接处理静态资源文件，那么在应用前端使用 CDN 将是最好的选择。</p><p>使用 CDN 的常见模式是把生产环境中的应用设置为“源”服务器，也就是说，当浏览器从 CDN 请求静态资源文件但缓存未命中时，CDN 将立即从“源”服务器中抓取该文件，并对其进行缓存。例如，假设我们在 <code>example.com</code> 上运行 Rails 应用，并在 <code>mycdnsubdomain.fictional-cdn.com</code> 上配置了 CDN，在处理对 <code>mycdnsubdomain.fictional-cdn.com/assets/smile.png</code> 的首次请求时，CDN 会抓取 <code>example.com/assets/smile.png</code> 并进行缓存。之后再请求 <code>mycdnsubdomain.fictional-cdn.com/assets/smile.png</code> 时，CDN 会直接提供缓存中的文件副本。对于任何请求，只要 CDN 能够直接处理，就不会访问 Rails 服务器。由于 CDN 提供的静态资源文件由地理位置最近的 CDN 服务器提供，因此对请求的响应更快，同时 Rails 服务器不再需要花费大量时间处理静态资源文件，因此可以专注于更快地处理应用代码。</p><p><a class="anchor" id="set-up-a-cdn-to-serve-static-assets"></a></p><h5 id="set-up-a-cdn-to-serve-static-assets">4.4.1 设置用于处理静态资源文件的 CDN</h5><p>要设置 CDN，首先必须在公开的互联网 URL 地址上（例如 <code>example.com</code>）以生产环境运行 Rails 应用。下一步，注册云服务提供商的 CDN 服务。然后配置 CDN 的“源”服务器，把它指向我们的网站 <code>example.com</code>，具体配置方法请参考云服务提供商的文档。</p><p>CDN 提供商会为我们的应用提供一个自定义子域名，例如 <code>mycdnsubdomain.fictional-cdn.com</code>（注意 <code>fictional-cdn.com</code> 只是撰写本文时杜撰的一个 CDN 提供商）。完成 CDN 服务器配置后，还需要告诉浏览器从 CDN 抓取静态资源文件，而不是直接从 Rails 服务器抓取。为此，需要在 Rails 配置中，用静态资源文件的主机代替相对路径。通过 <code>config/environments/production.rb</code> 配置文件的 <code>config.action_controller.asset_host</code> 选项，我们可以设置静态资源文件的主机：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.action_controller.asset_host = 'mycdnsubdomain.fictional-cdn.com'

</pre>
</div>
<div class="note"><p>这里只需提供“主机”，即前文提到的子域名，而不需要指定 HTTP 协议，例如 <code>http://</code> 或 <code>https://</code>。默认情况下，Rails 会使用网页请求的 HTTP 协议作为指向静态资源文件链接的协议。</p></div><p>还可以通过<a href="http://en.wikipedia.org/wiki/Environment_variable">环境变量</a>设置静态资源文件的主机，这样可以方便地在不同的运行环境中使用不同的静态资源文件：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.action_controller.asset_host = ENV['CDN_HOST']

</pre>
</div>
<div class="note"><p>这里还需要把服务器上的 <code>CDN_HOST</code> 环境变量设置为 <code>mycdnsubdomain.fictional-cdn.com</code>。</p></div><p>服务器和 CDN 配置好后，就可以像下面这样引用静态资源文件：</p><div class="code_container">
<pre class="brush: ruby; html-script: true; gutter: false; toolbar: false">
&lt;%= asset_path('smile.png') %&gt;

</pre>
</div>
<p>这时返回的不再是相对路径 <code>/assets/smile.png</code>（出于可读性考虑省略了文件名中的指纹），而是指向 CDN 的完整路径：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
http://mycdnsubdomain.fictional-cdn.com/assets/smile.png

</pre>
</div>
<p>如果 CDN 上有 <code>smile.png</code> 文件的副本，就会直接返回给浏览器，而 Rails 服务器甚至不知道有浏览器请求了 <code>smile.png</code> 文件。如果 CDN 上没有 <code>smile.png</code> 文件的副本，就会先从“源”服务器上抓取 <code>example.com/assets/smile.png</code> 文件，再返回给浏览器，同时保存文件的副本以备将来使用。</p><p>如果只想让 CDN 处理部分静态资源文件，可以在调用静态资源文件辅助方法时使用 <code>:host</code> 选项，以覆盖 <code>config.action_controller.asset_host</code> 选项中设置的值：</p><div class="code_container">
<pre class="brush: ruby; html-script: true; gutter: false; toolbar: false">
&lt;%= asset_path 'image.png', host: 'mycdnsubdomain.fictional-cdn.com' %&gt;

</pre>
</div>
<p><a class="anchor" id="customize-cdn-caching-behavior"></a></p><h5 id="customize-cdn-caching-behavior">4.4.2 自定义 CDN 缓存行为</h5><p>CDN 的作用是为内容提供缓存。如果 CDN 上有过期或不良内容，那么不仅不能对应用有所助益，反而会造成负面影响。本小节将介绍大多数 CDN 的一般缓存行为，而我们使用的 CDN 在特性上可能会略有不同。</p><p><a class="anchor" id="cdn-request-caching"></a></p><h6 id="cdn-request-caching">4.4.2.1 CDN 请求缓存</h6><p>我们常说 CDN 对于缓存静态资源文件非常有用，但实际上 CDN 缓存的是整个请求。其中既包括了静态资源文件的请求体，也包括了其首部。其中，<code>Cache-Control</code> 首部是最重要的，用于告知 CDN（和 Web 浏览器）如何缓存文件内容。假设用户请求了 <code>/assets/i-dont-exist.png</code> 这个并不存在的静态资源文件，并且 Rails 应用返回的是 404，那么只要设置了合法的 <code>Cache-Control</code> 首部，CDN 就会缓存 404 页面。</p><p><a class="anchor" id="cdn-header-debugging"></a></p><h6 id="cdn-header-debugging">4.4.2.2 调试 CDN 首部</h6><p>检查 CDN 是否正确缓存了首部的方法之一是使用 <a href="http://explainshell.com/explain?cmd=curl+-I+http%3A%2F%2Fwww.example.com">curl</a>。我们可以分别从 Rails 服务器和 CDN 获取首部，然后确认二者是否相同：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ curl -I http://www.example/assets/application-
d0e099e021c95eb0de3615fd1d8c4d83.css
HTTP/1.1 200 OK
Server: Cowboy
Date: Sun, 24 Aug 2014 20:27:50 GMT
Connection: keep-alive
Last-Modified: Thu, 08 May 2014 01:24:14 GMT
Content-Type: text/css
Cache-Control: public, max-age=2592000
Content-Length: 126560
Via: 1.1 vegur

</pre>
</div>
<p>CDN 中副本的首部：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ curl -I http://mycdnsubdomain.fictional-cdn.com/application-
d0e099e021c95eb0de3615fd1d8c4d83.css
HTTP/1.1 200 OK Server: Cowboy Last-
Modified: Thu, 08 May 2014 01:24:14 GMT Content-Type: text/css
Cache-Control:
public, max-age=2592000
Via: 1.1 vegur
Content-Length: 126560
Accept-Ranges:
bytes
Date: Sun, 24 Aug 2014 20:28:45 GMT
Via: 1.1 varnish
Age: 885814
Connection: keep-alive
X-Served-By: cache-dfw1828-DFW
X-Cache: HIT
X-Cache-Hits:
68
X-Timer: S1408912125.211638212,VS0,VE0

</pre>
</div>
<p>在 CDN 文档中可以查询 CDN 提供的额外首部，例如 <code>X-Cache</code>。</p><p><a class="anchor" id="cdns-and-the-cache-control-header"></a></p><h6 id="cdns-and-the-cache-control-header">4.4.2.3 CDN 和 <code>Cache-Control</code> 首部</h6><p><a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9">Cache-Control 首部</a>是一个 W3C 规范，用于描述如何缓存请求。当未使用 CDN 时，浏览器会根据 <code>Cache-Control</code> 首部来缓存文件内容。在静态资源文件未修改的情况下，浏览器就不必重新下载 CSS 或 JavaScript 等文件了。通常，Rails 服务器需要告诉 CDN（和浏览器）这些静态资源文件是“公共的”，这样任何缓存都可以保存这些文件的副本。此外，通常还会通过 <code>max-age</code> 字段来设置缓存失效前储存对象的时间。<code>max-age</code> 字段的单位是秒，最大设置为 31536000，即一年。在 Rails 应用中设置 <code>Cache-Control</code> 首部的方法如下：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.public_file_server.headers = {
  'Cache-Control' =&gt; 'public, max-age=31536000'
}

</pre>
</div>
<p>现在，在生产环境中，Rails 应用的静态资源文件在 CDN 上会被缓存长达 1 年之久。由于大多数 CDN 会缓存首部，静态资源文件的 <code>Cache-Control</code> 首部会被传递给请求该静态资源文件的所有浏览器，这样浏览器就会长期缓存该静态资源文件，直到缓存过期后才会重新请求该文件。</p><p><a class="anchor" id="cdns-and-url-based-cache-invalidation"></a></p><h6 id="cdns-and-url-based-cache-invalidation">4.4.2.4 CDN 和基于 URL 地址的缓存失效</h6><p>大多数 CDN 会根据完整的 URL 地址来缓存静态资源文件的内容。因此，缓存</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
http://mycdnsubdomain.fictional-cdn.com/assets/smile-123.png

</pre>
</div>
<p>和缓存</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
http://mycdnsubdomain.fictional-cdn.com/assets/smile.png

</pre>
</div>
<p>被认为是两个完全不同的静态资源文件的缓存。</p><p>如果我们把 <code>Cache-Control</code> HTTP 首部的 <code>max-age</code> 值设得很大，那么当静态资源文件的内容发生变化时，应同时使原有缓存失效。例如，当我们把黄色笑脸图像更换为蓝色笑脸图像时，我们希望网站的所有访客看到的都是新的蓝色笑脸图像。如果我们使用了 CDN，并使用了 Rails Asset Pipeline <code>config.assets.digest</code> 选项的默认值 <code>true</code>，一旦静态资源文件的内容发生变化，其文件名就会发生变化。这样，我们就不需要每次手动使某个静态资源文件的缓存失效。通过使用唯一的新文件名，我们就能确保用户访问的总是静态资源文件的最新版本。</p><p><a class="anchor" id="customizing-the-pipeline"></a></p><h3 id="customizing-the-pipeline">5 自定义 Asset Pipeline</h3><p><a class="anchor" id="css-compression"></a></p><h4 id="css-compression">5.1 压缩 CSS</h4><p>压缩 CSS 的可选方式之一是使用 YUI。通过 <a href="http://yui.github.io/yuicompressor/css.html">YUI CSS 压缩器</a>可以缩小 CSS 文件的大小。</p><p>在 Gemfile 中添加 <code>yui-compressor</code> gem 后，通过下面的设置可以启用 YUI 压缩：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.css_compressor = :yui

</pre>
</div>
<p>如果我们在 Gemfile 中添加了 <code>sass-rails</code> gem，那么也可以使用 Sass 压缩：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.css_compressor = :sass

</pre>
</div>
<p><a class="anchor" id="javascript-compression"></a></p><h4 id="javascript-compression">5.2 压缩 JavaScript</h4><p>压缩 JavaScript 的可选方式有 <code>:closure</code>、<code>:uglifier</code> 和 <code>:yui</code>，分别要求在 Gemfile 中添加 <code>closure-compiler</code>、<code>uglifier</code> 和 <code>yui-compressor</code> gem。</p><p>默认情况下，Gemfile 中包含了 <a href="https://github.com/lautis/uglifier">uglifier</a> gem，这个 gem 使用 Ruby 包装 <a href="https://github.com/mishoo/UglifyJS">UglifyJS</a>（使用 NodeJS 开发），作用是通过删除空白和注释、缩短局部变量名及其他微小优化（例如在可能的情况下把 <code>if&amp;#8230;&amp;#8203;else</code> 语句修改为三元运算符）压缩 JavaScript 代码。</p><p>使用 <code>uglifier</code> 压缩 JavaScript 需进行如下设置：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.js_compressor = :uglifier

</pre>
</div>
<div class="note"><p>要使用 <code>uglifier</code> 压缩 JavaScript，就必须安装支持 <a href="https://github.com/rails/execjs#readme">ExecJS</a> 的运行时。macOS 和 Windows 已经预装了此类运行时。</p></div><p><a class="anchor" id="serving-gzipped-version-of-assets"></a></p><h4 id="serving-gzipped-version-of-assets">5.3 用 GZip 压缩静态资源文件</h4><p>默认情况下，Sprockets 会用 GZip 压缩编译后的静态资源文件，同时也会保留未压缩的版本。通过 GZip 压缩可以减少对带宽的占用。设置 GZip 压缩的方式如下：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.gzip = false # 禁止用 GZip 压缩静态资源文件

</pre>
</div>
<p><a class="anchor" id="using-your-own-compressor"></a></p><h4 id="using-your-own-compressor">5.4 自定义压缩工具</h4><p>在设置 CSS 和 JavaScript 压缩工具时还可以使用对象。这个对象要能响应 <code>compress</code> 方法，这个方法接受一个字符串作为唯一参数，并返回一个字符串。</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class Transformer
  def compress(string)
    do_something_returning_a_string(string)
  end
end

</pre>
</div>
<p>要使用这个压缩工具，需在 <code>application.rb</code> 配置文件中做如下设置：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.css_compressor = Transformer.new

</pre>
</div>
<p><a class="anchor" id="changing-the-assets-path"></a></p><h4 id="changing-the-assets-path">5.5 修改静态资源文件的路径</h4><p>默认情况下，Sprockets 使用 <code>/assets</code> 作为静态资源文件的公开路径。</p><p>我们可以修改这个路径：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.prefix = "/some_other_path"

</pre>
</div>
<p>通过这种方式，在升级未使用 Asset Pipeline 但使用了 <code>/assets</code> 路径的老项目时，我们就可以轻松为新的静态资源文件设置另一个公开路径。</p><p><a class="anchor" id="x-sendfile-headers"></a></p><h4 id="x-sendfile-headers">5.6 <code>X-Sendfile</code> 首部</h4><p><code>X-Sendfile</code> 首部的作用是让 Web 服务器忽略应用对请求的响应，直接返回磁盘中的指定文件。默认情况下 Rails 不会发送这个首部，但在支持这个首部的服务器上可以启用这一特性，以提供更快的响应速度。关于这一特性的更多介绍，请参阅 <a href="http://api.rubyonrails.org/v5.1.1/classes/ActionController/DataStreaming.html#method-i-send_file"><code>send_file</code> 方法的文档</a>。</p><p>Apache 和 NGINX 支持 <code>X-Sendfile</code> 首部，启用方法是在 <code>config/environments/production.rb</code> 配置文件中进行设置：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
# config.action_dispatch.x_sendfile_header = "X-Sendfile" # 用于 Apache
# config.action_dispatch.x_sendfile_header = 'X-Accel-Redirect' # 用于 NGINX

</pre>
</div>
<div class="warning"><p>要想在升级现有应用时使用上述选项，可以把这两行代码粘贴到 <code>production.rb</code> 配置文件中，或其他类似的生产环境配置文件中。</p></div><div class="info"><p>更多介绍请参阅生产服务器的相关文档：<a href="https://tn123.org/mod_xsendfile/">Apache</a>、<a href="http://wiki.nginx.org/XSendfile">NGINX</a>。</p></div><p><a class="anchor" id="assets-cache-store"></a></p><h3 id="assets-cache-store">6 静态资源文件缓存的存储方式</h3><p>在开发环境和生产环境中，Sprockets 默认在 <code>tmp/cache/assets</code> 文件夹中缓存静态资源文件。修改这一设置的方式如下：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.configure do |env|
  env.cache = ActiveSupport::Cache.lookup_store(:memory_store,
                                                { size: 32.megabytes })
end

</pre>
</div>
<p>禁用静态资源文件缓存的方式如下：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.configure do |env|
  env.cache = ActiveSupport::Cache.lookup_store(:null_store)
end

</pre>
</div>
<p><a class="anchor" id="adding-assets-to-your-gems"></a></p><h3 id="adding-assets-to-your-gems">7 通过 gem 添加静态资源文件</h3><p>我们还可以通过 gem 添加静态资源文件。</p><p>为 Rails 提供标准 JavaScript 库的 <code>jquery-rails</code> gem 就是很好的例子。这个 gem 中包含了继承自 <code>Rails::Engine</code> 类的引擎类，这样 Rails 就知道这个 gem 中可能包含静态资源文件，于是会把其中的 <code>app/assets</code>、<code>lib/assets</code> 和 <code>vendor/assets</code> 文件夹添加到 Sprockets 的搜索路径中。</p><p><a class="anchor" id="making-your-library-or-gem-a-pre-processor"></a></p><h3 id="making-your-library-or-gem-a-pre-processor">8 使用代码库或 gem 作为预处理器</h3><p>Sprockets 使用 Processors、Transformers、Compressors 和 Exporters 扩展功能。详情参阅“<a href="https://github.com/rails/sprockets/blob/master/guides/extending_sprockets.md">Extending Sprockets</a>”一文。下述示例注册一个预处理器，在 text/css 文件（.css）默认添加一个注释。</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
module AddComment
  def self.call(input)
    { data: input[:data] + "/* Hello From my sprockets extension */" }
  end
end

</pre>
</div>
<p>有了修改输入数据的模块后，还要把它注册为指定 MIME 类型的预处理器：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
Sprockets.register_preprocessor 'text/css', AddComment

</pre>
</div>
<p><a class="anchor" id="upgrading-from-old-versions-of-rails"></a></p><h3 id="upgrading-from-old-versions-of-rails">9 从旧版本的 Rails 升级</h3><p>从 Rails 3.0 或 Rails 2.x 升级时有一些问题需要解决。首先，要把 <code>public/</code> 文件夹中的文件移动到新位置。关于不同类型文件储存位置的介绍，请参阅 <a href="#asset-organization">静态资源文件的组织方式</a>。</p><p>其次，要避免出现重复的 JavaScript 文件。从 Rails 3.1 开始，jQuery 成为默认的 JavaScript 库，Rails 会自动加载 <code>jquery.js</code>，不再需要手动把 <code>jquery.js</code> 复制到 <code>app/assets</code> 文件夹中。</p><p>再次，要使用正确的默认选项更新各种环境配置文件。</p><p>在 <code>application.rb</code> 配置文件中：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
# 静态资源文件的版本，通过修改这个选项可以使原有的静态资源文件缓存全部过期
config.assets.version = '1.0'

# 通过 onfig.assets.prefix = "/assets" 修改静态资源文件的路径

</pre>
</div>
<p>在 <code>development.rb</code> 配置文件中：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
# 展开用于加载静态资源文件的代码
config.assets.debug = true

</pre>
</div>
<p>在 <code>production.rb</code> 配置文件中：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
# 选择（可用的）压缩工具
config.assets.js_compressor = :uglifier
# config.assets.css_compressor = :yui

# 在找不到已编译的静态资源文件的情况下，不退回到 Asset Pipeline
config.assets.compile = false

# 为静态资源文件的 URL 地址生成指纹
config.assets.digest = true

# 预编译附加的静态资源文件（application.js、application.css 和所有
# 已添加的非 JS/CSS 文件）
# config.assets.precompile += %w( admin.js admin.css )

</pre>
</div>
<p>Rails 4 及更高版本不会再在 <code>test.rb</code> 配置文件中添加 Sprockets 的默认设置，因此需要手动完成。需要添加的默认设置包括 <code>config.assets.compile = true</code>、<code>config.assets.compress = false</code>、<code>config.assets.debug = false</code> 和 <code>config.assets.digest = false</code>。</p><p>最后，还要在 Gemfile 中加入下列 gem：</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
gem 'sass-rails',   "~&gt; 3.2.3"
gem 'coffee-rails', "~&gt; 3.2.1"
gem 'uglifier'

</pre>
</div>


        <h3>反馈</h3>
        <p>
          我们鼓励您帮助提高本指南的质量。
        </p>
        <p>
          如果看到如何错字或错误，请反馈给我们。
          您可以阅读我们的<a href="http://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html#contributing-to-the-rails-documentation">文档贡献</a>指南。
        </p>
        <p>
          您还可能会发现内容不完整或不是最新版本。
          请添加缺失文档到 master 分支。请先确认 <a href="http://edgeguides.rubyonrails.org">Edge Guides</a> 是否已经修复。
          关于用语约定，请查看<a href="ruby_on_rails_guides_guidelines.html">Ruby on Rails 指南指导</a>。
        </p>
        <p>
          无论什么原因，如果你发现了问题但无法修补它，请<a href="https://github.com/rails/rails/issues">创建 issue</a>。
        </p>
        <p>
          最后，欢迎到 <a href="http://groups.google.com/group/rubyonrails-docs">rubyonrails-docs 邮件列表</a>参与任何有关 Ruby on Rails 文档的讨论。
        </p>
        <h4>中文翻译反馈</h4>
        <p>贡献：<a href="https://github.com/ruby-china/guides">https://github.com/ruby-china/guides</a>。</p>
      </div>
    </div>
  </div>

  <hr class="hide" />
  <div id="footer">
    <div class="wrapper">
      <p>本著作采用 <a href="https://creativecommons.org/licenses/by-sa/4.0/">创作共用 署名-相同方式共享 4.0 国际</a> 授权</p>
<p>“Rails”，“Ruby on Rails”，以及 Rails Logo 为 David Heinemeier Hansson 的商标。版权所有</p>

    </div>
  </div>

  <script type="text/javascript" src="javascripts/jquery.min.js"></script>
  <script type="text/javascript" src="javascripts/responsive-tables.js"></script>
  <script type="text/javascript" src="javascripts/guides.js"></script>
  <script type="text/javascript" src="javascripts/syntaxhighlighter.js"></script>
  <script type="text/javascript">
    syntaxhighlighterConfig = {
      autoLinks: false,
    };
    $(guidesIndex.bind);
  </script>
</body>
</html>
